Skip to main content

Preparing the App

These are the changes in the app's repository. The exact code for each step is in the package's README (packages/abair-i18n/README.md in the translations-editor repository). This page explains what each step is for.

1. Install the package​

The app uses the @abair/i18n package, published to ABAIR's Gitea package registry rather than the public npm registry.

  • Commit an .npmrc that sends the @abair scope to the Gitea registry.
  • Installing needs a token with read access to packages. Keep it out of the repo: on your machine, in your own npm config; in CI and Docker builds, as a secret.

2. Keep only English in the repo​

Keep one English file, such as locales/en.json, holding just the English, grouped by namespace. There is no Irish file in the repo: the Irish lives in the editor.

3. Build the Irish in​

Before every build, a step downloads the Irish for the branch being built from the editor into a generated file, such as locales/ga-IE.json. Add that file to .gitignore.

  • The app loads the English file and the generated Irish file into i18next as its two languages, with English as the fallback. An untranslated string then shows in English.
  • Tell the build which branch it is building, so each site gets its own branch's Irish.
  • In deploys, fail the build if the Irish can't be downloaded, so a site is never deployed without Irish. The live site stays as it was until the deploy is run again.
  • Locally, never fail: keep the last copy, or use English the first time.
  • Run the same step before the dev server starts, and give developers a command to refresh it. See Irish in Local Development.

An app can instead load its Irish live in the browser, so a save shows up within a minute with no deploy. That puts a request to the editor on every page load, so building it in is the recommended setup. See How It Works.

4. Connect the live preview​

Connect i18next to the editor with the package, giving it the project's name in the editor. As the Irish is already built in, turn off its own loading of the Irish, so it only connects the preview.

This changes nothing for visitors. The preview only switches on when the editor shows the site in its frame.

5. Let the editor show the site​

The live preview opens the site in a frame on translations.abair.ie. The site's server must allow that:

  • add https://translations.abair.ie to the frame-ancestors part of its Content Security Policy;
  • remove any X-Frame-Options header, which would block it;
  • serve the site over https, since a browser won't frame an http site inside the editor.

For sites behind ABAIR's nginx, these headers are in the infrastructure repository and change through a pull request.

6. Make the deploy runnable on demand​

So that translators' saved Irish can go live without a code push:

  • Allow the deploy workflow to be started by hand for a chosen branch. The editor's Publish button starts it.
  • Make sure a rebuild of the same commit gets fresh Irish. A build cache can otherwise reuse the old download.
  • Optionally, add a scheduled rebuild, for example nightly, as a safety net for anything not published. It can skip a branch whose Irish hasn't changed since its last deploy.

7. Tell developers how it works​

Add a short Translations section to the app's README:

  • English goes in the English file, and only English.
  • Irish is done in the editor, never in the repo.
  • How and when Irish reaches the site.
  • How to get the Irish locally, and how to refresh it.

The Adding Text page can be linked from there.

8. Get package updates​

Add the app to the list of apps that use the package, in the translations-editor repository. Each new release of the package then opens a pull request in the app moving it to the new version. Merging it deploys the app as usual.